@nbtca/prompt 1.4.2 → 1.5.1

package/README.md

@@ -1,89 +1,58 @@
 # NBTCA Prompt
 
-Terminal-based information system for the NBTCA community.
+Terminal client for NBTCA events, documentation, status and personal timetables.
 
 [![npm version](https://img.shields.io/npm/v/@nbtca/prompt)](https://www.npmjs.com/package/@nbtca/prompt)
 [![License](https://img.shields.io/npm/l/@nbtca/prompt)](LICENSE)
 
+## Requirements
+
+- Node.js 20.12 or newer
+
 ## Install
 
 ```bash
-npm install -g @nbtca/prompt
+npm install --global @nbtca/prompt
+nbtca
 ```
 
-Or run directly:
+Run a command without installing:
 
 ```bash
-npx @nbtca/prompt
+npx @nbtca/prompt --help
 ```
 
-## Personal timetable
+## Commands
 
-Prompt owns the school login and local session; `@nbtca/nbtcal` owns timetable
-normalization and ICS generation.
-
-For a persistent local session:
-
-```bash
+```text
+nbtca events [--json]
+nbtca docs
+nbtca status
 nbtca schedule login
 nbtca schedule terms
 nbtca schedule export --term=2026:3 --week-one=YYYY-MM-DD
 nbtca schedule logout
 ```
 
-For a single run that neither reads nor saves a session (`--no-save` is an
-alias):
+Use `--plain` for stable output without color. `schedule export --one-shot`
+avoids reading or saving a campus session.
+
+Prompt never stores passwords. Persisted sessions contain only a masked account
+hint and a CookieJar, protected with user-only permissions on POSIX systems.
+Treat exported calendars and session files as private data. See [SECURITY.md](SECURITY.md).
+
+## Development
 
 ```bash
-npx @nbtca/prompt schedule export --one-shot
+npm ci
+npm run check
 ```
 
-Both the student id and password are masked in the terminal. The password is
-never saved. A persistent login stores only a masked account hint and the
-CookieJar in the user's state directory:
-
-- Unix/macOS default: `~/.local/state/nbtca/session.json`
-- Windows default: `%LOCALAPPDATA%/nbtca/session.json`
-- `$XDG_STATE_HOME` is honored when it is an absolute path
-
-On POSIX systems the directory is `0700` and the file is `0600`. `npx`, a local
-installation and a global installation therefore share the same state without
-depending on npm's disposable package cache. The session is a bearer secret;
-use `--one-shot` on shared machines and `schedule logout` when finished.
-Saved sessions use a sliding seven-day local expiry and are cleared immediately
-when the school reports that they have expired.
-
-JWXT currently returns week numbers and period times but not the first calendar
-date of a term. When no authoritative date map is available, Prompt asks for
-the first teaching Monday or accepts `--week-one=YYYY-MM-DD`. Confirm it against
-the official school calendar; Prompt will not guess. A slider or other browser
-challenge is also never bypassed—the CLI stops with an actionable message.
-Without an authoritative date map, the result is a base teaching-week schedule:
-holidays, make-up classes and temporary changes still require school notices.
-
-## Documentation
-
-Project documentation has been moved to the GitHub Wiki.
-
-- [Home](https://github.com/nbtca/Prompt/wiki)
-- [Getting Started](https://github.com/nbtca/Prompt/wiki/Getting-Started)
-- [Development Guide](https://github.com/nbtca/Prompt/wiki/Development-Guide)
-- [Terminal UX](https://github.com/nbtca/Prompt/wiki/Terminal-UX)
-- [Release Notes](https://github.com/nbtca/Prompt/wiki/Release-Notes)
-- [Features](https://github.com/nbtca/Prompt/wiki/Features)
-- [Terminal Compatibility](https://github.com/nbtca/Prompt/wiki/Terminal-Compatibility)
-- [FAQ](https://github.com/nbtca/Prompt/wiki/FAQ)
-
-## Requirements
+`check` runs formatting, lint, full TypeScript validation, tests, build, package
+consumer checks and dependency audit.
 
-- Node.js >= 20.12.0
+Project guides and release notes live in the [Wiki](https://github.com/nbtca/Prompt/wiki).
 
 ## License
 
 MIT
-
-## Links
-
-- Website: https://nbtca.space
-- GitHub: https://github.com/nbtca
-- NPM: https://www.npmjs.com/package/@nbtca/prompt

package/SECURITY.md

@@ -1,47 +1,18 @@
 # Security Policy
 
-## School credentials
-
-Prompt sends the student id and an in-memory encrypted password only to the
-school's WebVPN/CAS login flow. It does not offer `--password`, password
-environment variables or credential files. Password and verification input is
-masked and is never written to preferences, state, cache, ICS or logs.
-
-If the school requests a slider, OTP, FIDO or another browser challenge, Prompt
-fails closed. It does not automate or bypass the challenge.
-
-## Authenticated transport
-
-Authentication redirects are restricted to exact HTTPS hosts and routes for
-the campus WebVPN, authentication service and JWXT. CAS `service` and
-WebVPN `origin` parameters are validated against explicit callback routes.
-Caller-supplied `Cookie`, `Authorization` and `Host` headers are rejected.
-
-Errors expose only stable local codes and stages. Response bodies, redirect
-queries, cookies, encrypted passwords and underlying network error objects are
-not included in user-facing output.
-
-## Persisted session
-
-The optional persisted CookieJar is a bearer secret. It is stored under the
-user's state directory with a versioned schema, an atomic write, a `0700`
-directory and a `0600` file on POSIX systems. The saved account hint is masked,
-and Prompt never adds the full student id or password to the state schema. The
-opaque school cookies must still be treated as bearer secrets. Sessions have a
-sliding seven-day local expiry.
-
-Use `nbtca schedule logout` to clear it. Use `--one-shot` on a shared or
-untrusted computer so no session is read or written.
-
-## Timetable and ICS privacy
-
-Raw JWXT responses are processed in memory. Only timetable fields needed for
-normalization are passed to `@nbtca/nbtcal`; the student profile object is
-discarded. Generated ICS files can reveal a person's location and routine, so
-they are created with mode `0600` where supported and should not be uploaded to
-public or "secret-link" hosting.
-
-## Reporting vulnerabilities
-
-Use the repository's GitHub Security Advisory page. Do not include credentials,
-cookies, raw school responses or a personal ICS in a public issue.
+Prompt sends credentials only to the allowlisted campus WebVPN and CAS login
+flow. Passwords stay in memory, are masked during entry and are never accepted
+through flags, environment variables or files. Interactive browser challenges
+fail closed.
+
+An optional persisted CookieJar is a bearer secret. Prompt writes it atomically
+to the user's state directory with `0700` directory and `0600` file permissions
+on POSIX systems. Use `nbtca schedule logout` to remove it, or `--one-shot` to
+avoid reading or writing a session.
+
+Exported calendars may reveal a person's routine and location. Keep session and
+ICS files private.
+
+Report vulnerabilities through GitHub Security Advisories. Never include
+credentials, cookies, raw campus responses or personal calendars in public
+issues.

package/dist/app/app.js

@@ -1,24 +1,14 @@
 import { ansi, ensureCursorRestored } from '../core/canvas.js';
-import { composeFrame, computeBodyRows } from './frame.js';
-import { routeGlobalKey } from './keys.js';
-import { renderHeader, renderFooter, HEADER_LINES, FOOTER_LINES } from './chrome.js';
+import { composeFrameLines, computeBodyRows, diffFrame } from './frame.js';
+import { isPrintableKey, KeyStreamDecoder, routeGlobalKey } from './keys.js';
+import { renderHeader, renderFooter, resolveChromeLayout } from './chrome.js';
 import { homeView } from './views/home.js';
 import { scheduleView } from './views/schedule.js';
 import { docsView } from './views/docs.js';
 import { eventsView } from './views/events.js';
 import { settingsView } from './views/settings.js';
 import { getAppTabs } from './tabs.js';
-/**
- * Event-driven full-screen app loop. Owns the alt-screen + raw-mode lifecycle
- * and composes every tab as a native `View` rendered in place. `ctx.runClassic`
- * remains as a scoped escape hatch a view can call itself when a single action
- * genuinely needs the real terminal (e.g. Docs handing off to glow/less to
- * read a file) — the app loop no longer dispatches whole tabs through it.
- *
- * Resolves once the user quits (q / Ctrl+C / Esc from home). Terminal state
- * (alt-screen, raw mode, cursor) is always restored before this resolves,
- * on SIGINT, on process exit, and even if an unexpected error is thrown.
- */
+import { SPINNER_FRAME_MS } from '../core/components/spinner.js';
 export async function runApp() {
     if (!process.stdin.isTTY || !process.stdout.isTTY)
         return;
@@ -26,8 +16,14 @@ export async function runApp() {
     let scroll = 0;
     let running = true;
     let suspended = false;
+    let entered = false;
+    const lifecycle = new AbortController();
+    const keyDecoder = new KeyStreamDecoder();
+    let keyFlushTimer;
+    let clockTimer;
+    let busyTimer;
+    let painted;
     const viewIds = getAppTabs().map((tab) => tab.id);
-    // Every tab is a native View rendered in place inside the alt-screen frame.
     const nativeViews = {
         home: homeView,
         schedule: scheduleView,
@@ -35,16 +31,42 @@ export async function runApp() {
         events: eventsView,
         settings: settingsView,
     };
+    const pendingLoads = new Map();
+    function loadView(id) {
+        const target = nativeViews[id];
+        if (!target?.load || pendingLoads.has(id))
+            return;
+        const pending = target
+            .load(ctx)
+            .catch(() => undefined)
+            .finally(() => pendingLoads.delete(id));
+        pendingLoads.set(id, pending);
+    }
     function size() {
         return { rows: process.stdout.rows || 24, cols: process.stdout.columns || 80 };
     }
     const ctx = {
-        get size() { return size(); },
-        get bodyRows() { return computeBodyRows(size().rows, HEADER_LINES, FOOTER_LINES); },
-        rerender() { render(); },
-        resetScroll() { scroll = 0; },
-        runClassic(fn) { return runClassic(fn); },
-        quit() { quit(); },
+        signal: lifecycle.signal,
+        get size() {
+            return size();
+        },
+        get bodyRows() {
+            const { rows } = size();
+            const chrome = resolveChromeLayout(rows);
+            return computeBodyRows(rows, chrome.headerLines, chrome.footerLines);
+        },
+        rerender() {
+            render();
+        },
+        resetScroll() {
+            scroll = 0;
+        },
+        runClassic(fn) {
+            return runClassic(fn);
+        },
+        quit() {
+            quit();
+        },
     };
     function render() {
         if (suspended || !running)
@@ -52,24 +74,38 @@ export async function runApp() {
         const { rows, cols } = size();
         const active = nativeViews[view];
         const tabs = getAppTabs();
-        const header = renderHeader(tabs, view, cols);
-        const footer = renderFooter(view, cols, tabs.length, active?.footerHint?.(tabs.length, cols));
+        const chrome = resolveChromeLayout(rows);
+        const header = renderHeader(tabs, view, cols, chrome.headerLines);
+        const footer = renderFooter(view, cols, tabs.length, active?.footerHint?.(tabs.length, cols), chrome.footerLines);
         const body = active?.render(ctx) ?? [];
-        process.stdout.write(ansi.home + composeFrame(header, body, footer, rows, cols, scroll) + ansi.eraseDown);
+        const bodyScroll = active?.capturesInput?.() ? Number.MAX_SAFE_INTEGER : scroll;
+        const lines = composeFrameLines(header, body, footer, rows, cols, bodyScroll);
+        const patch = diffFrame(painted?.cols === cols ? painted.lines : undefined, lines);
+        painted = { cols, lines };
+        if (patch)
+            process.stdout.write(patch);
+        scheduleBusyTick(active?.isBusy?.() === true);
     }
-    function onKey(data) {
-        const key = data.toString();
+    function scheduleBusyTick(busy) {
+        if (busy && running && busyTimer === undefined) {
+            busyTimer = setTimeout(() => {
+                busyTimer = undefined;
+                render();
+            }, SPINNER_FRAME_MS);
+            return;
+        }
+        if (busy || busyTimer === undefined)
+            return;
+        clearTimeout(busyTimer);
+        busyTimer = undefined;
+    }
+    function dispatchKey(key) {
         if (key === '\x03') {
+            process.exitCode = 130;
             quit();
             return;
         } // Ctrl-C always quits, even mid-capture.
         const active = nativeViews[view];
-        // Esc always reaches global routing, even while a view "captures" input
-        // for a focused field (login/search text entry). Without this carve-out,
-        // a view whose own Esc-handling doesn't escape its captured mode would
-        // trap the user on that tab with no way out except Ctrl-C (quitting the
-        // whole app). Esc must never be swallowed silently — it's the universal
-        // way out of anything.
         if (active?.capturesInput?.() && key !== '\x1b') {
             active.handleKey?.(key, ctx);
             render();
@@ -81,17 +117,13 @@ export async function runApp() {
             return;
         }
         if (g.back) {
-            // Esc steps back one level within the view first (e.g. its week grid
-            // back to its own hub) — only once the view has nowhere left to step
-            // back to does Esc leave the tab for Home. Matches how k9s/lazygit
-            // treat Esc: back one level, not straight to the root.
             if (active?.handleBack?.(ctx)) {
                 scroll = 0; // the new sub-view's content height has nothing to do with the old one's
                 render();
                 return;
             }
             view = 'home';
-            void nativeViews['home']?.load?.(ctx)?.catch(() => { });
+            loadView('home');
             render();
             return;
         }
@@ -100,9 +132,12 @@ export async function runApp() {
             return;
         }
         if (g.scrollBy) {
-            // fitBody (frame.ts) clamps this to [0, content.length - bodyRows]
-            // on every render regardless of what's requested here, so this never
-            // needs to know the current body's height to stay in bounds.
+            if (active?.capturesPageKeys?.()) {
+                active.handleKey?.(key, ctx);
+                scroll = 0;
+                render();
+                return;
+            }
             const page = Math.max(1, ctx.bodyRows - 2);
             scroll = Math.max(0, scroll + g.scrollBy * page);
             render();
@@ -111,35 +146,85 @@ export async function runApp() {
         active?.handleKey?.(key, ctx);
         render();
     }
+    function dispatchKeys(keys) {
+        for (let index = 0; index < keys.length && running && !suspended; index += 1) {
+            let key = keys[index];
+            if (key === undefined)
+                continue;
+            if (nativeViews[view]?.capturesInput?.() && isPrintableKey(key)) {
+                while (index + 1 < keys.length) {
+                    const next = keys[index + 1];
+                    if (next === undefined || !isPrintableKey(next))
+                        break;
+                    key += next;
+                    index += 1;
+                }
+            }
+            dispatchKey(key);
+        }
+    }
+    function scheduleClock() {
+        if (!running)
+            return;
+        clockTimer = setTimeout(() => {
+            clockTimer = undefined;
+            render();
+            scheduleClock();
+        }, 60_000 - (Date.now() % 60_000));
+    }
+    function clearKeyFlush() {
+        if (keyFlushTimer === undefined)
+            return;
+        clearTimeout(keyFlushTimer);
+        keyFlushTimer = undefined;
+    }
+    function onKey(data) {
+        clearKeyFlush();
+        dispatchKeys(keyDecoder.write(data));
+        if (!running || suspended || !keyDecoder.hasPending)
+            return;
+        keyFlushTimer = setTimeout(() => {
+            keyFlushTimer = undefined;
+            dispatchKeys(keyDecoder.flush());
+        }, 20);
+    }
     function enter() {
+        if (entered || lifecycle.signal.aborted)
+            return;
+        entered = true;
+        painted = undefined;
+        keyDecoder.reset();
         ensureCursorRestored();
-        process.stdout.write(ansi.enterAlt + ansi.hideCursor);
-        if (process.stdin.isTTY)
-            process.stdin.setRawMode(true);
-        process.stdin.resume();
-        process.stdin.on('data', onKey);
+        try {
+            process.stdout.write(ansi.enterAlt + ansi.hideCursor);
+            if (process.stdin.isTTY)
+                process.stdin.setRawMode(true);
+            process.stdin.resume();
+            process.stdin.on('data', onKey);
+        }
+        catch (error) {
+            leave();
+            throw error;
+        }
     }
     function leave() {
+        if (!entered)
+            return;
+        entered = false;
+        clearKeyFlush();
+        keyDecoder.reset();
         process.stdin.removeListener('data', onKey);
         if (process.stdin.isTTY)
             process.stdin.setRawMode(false);
         process.stdout.write(ansi.showCursor + ansi.leaveAlt);
-        // `enter()` calls `stdin.resume()`; a resumed stdin stream keeps the
-        // Node event loop alive by design even with no listeners attached. The
-        // classic bridge calls `enter()` again right after, so pausing here is
-        // always safe — either it's about to be resumed, or the app is quitting
-        // for good and this is what lets the process actually exit.
         process.stdin.pause();
     }
     function switchTo(id) {
         scroll = 0;
         view = id;
-        void nativeViews[id]?.load?.(ctx)?.catch(() => { });
+        loadView(id);
         render();
     }
-    // A classic surface (currently only Docs' glow/less pager) owns its own
-    // raw-mode + rendering, so the app must fully leave() the alt-screen
-    // before invoking it and re-enter() after it returns.
     async function runClassic(fn) {
         suspended = true;
         leave();
@@ -147,11 +232,10 @@ export async function runApp() {
             await fn();
         }
         catch (err) {
-            // Classic surfaces are expected to surface their own errors, but if
-            // one throws anyway, don't swallow it silently: leave() has already
-            // restored cooked mode, so writing to stderr here is visible.
             process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
         }
+        if (!running)
+            return;
         enter();
         suspended = false;
         render();
@@ -163,10 +247,18 @@ export async function runApp() {
         leave();
     }
     function onSigint() {
+        process.exitCode = 130;
+        quit();
+    }
+    function onSigterm() {
+        process.exitCode = 143;
         quit();
-        process.exit(0);
     }
-    let resolveRun = () => { };
+    function onSighup() {
+        process.exitCode = 129;
+        quit();
+    }
+    let resolveRun;
     const done = new Promise((resolve) => {
         resolveRun = resolve;
     });
@@ -174,6 +266,12 @@ export async function runApp() {
         if (!running)
             return;
         running = false;
+        lifecycle.abort();
+        if (clockTimer !== undefined) {
+            clearTimeout(clockTimer);
+            clockTimer = undefined;
+        }
+        scheduleBusyTick(false);
         try {
             leave();
         }
@@ -181,22 +279,27 @@ export async function runApp() {
             process.stdout.removeListener('resize', onResize);
             process.removeListener('exit', onExit);
             process.removeListener('SIGINT', onSigint);
+            process.removeListener('SIGTERM', onSigterm);
+            process.removeListener('SIGHUP', onSighup);
             resolveRun();
         }
     }
     process.on('exit', onExit);
     process.stdout.on('resize', onResize);
     process.once('SIGINT', onSigint);
+    process.once('SIGTERM', onSigterm);
+    process.once('SIGHUP', onSighup);
     try {
         enter();
-        void nativeViews['home']?.load?.(ctx)?.catch(() => { });
+        loadView('home');
         render();
+        scheduleClock();
         await done;
     }
     finally {
-        // Safety net: if we got here via an unexpected throw rather than quit(),
-        // make sure the terminal is restored and listeners don't leak.
-        if (running)
-            quit();
+        quit();
+        await Promise.allSettled(Object.values(nativeViews).map(async (target) => {
+            await target.dispose?.();
+        }));
     }
 }